MCP 完全指南

你写了三个 Agent:一个查 GitLab,一个查数据库,一个读文件系统。现在产品说"再接个 Slack 通知"。你翻出第四个 Agent 的工具注册代码,复制粘贴、改函数签名、重新处理鉴权、再写一遍错误处理——第四次干这件事了。

问题不在于工具难写,而在于每个 Agent 都要为每个数据源单独写一遍对接代码。M 个 Agent 对接 N 个数据源,就是 M×N 份胶水代码,谁改谁崩。

MCP 的一句话概括:它是 Agent 世界的 USB-C——把"每个 Agent 对接每个工具"的 M×N 集成地狱,变成"工具说一次标准语,所有 Agent 都能用"的 M+N。

这篇讲清楚 MCP 到底是什么、协议长什么样、怎么从零手搓一个 server 接到你自己的 Agent 循环上、官方 SDK 怎么用、2026 年协议的重大变化,以及它和 A2A 的分工。全程配可运行的 Go 代码。


一、MCP 是什么:不是又一个框架,是一根协议

先说人话:MCP(Model Context Protocol)是一套标准协议,规定"Agent 怎么向外部工具/数据要东西"。 它不帮你写 Agent,也不帮你写工具,它只规定两者之间说话的格式。

类比 USB-C:以前每个设备一根专用线(Type-A、Micro-B、Lightning、圆口电源……),换设备就换线。USB-C 出现后,一根线插所有设备。MCP 就是 Agent 和工具之间的那根 USB-C——工具按 MCP 标准暴露一次能力,任何支持 MCP 的 Agent(Claude Desktop、Cursor、你自己手搓的循环)都能直接用。

MCP 定义了三种「原语」,对应三种不同的控制权:

原语 是什么 谁控制 例子
Tools 可被模型调用的函数 模型决定何时调 get_weather、run_sql、send_slack
Resources 可被读取的数据/文件 应用决定加载哪些 一个文件的内容、一段数据库 schema
Prompts 预置的提示词模板 用户主动触发 一个 /review 斜杠命令背后的模板

这三层和整个系列的分工能对上:本篇的 Tools 就是第 03 篇讲的工具设计,只是换成跨进程的标准协议;Prompts 的思想和第 11 篇的 Skills 一脉相承(预置流程);Resources 则是把第 06 篇的检索结果标准化地喂进上下文。

本篇聚焦最常用、也最能说清协议本质的 Tools。 搞懂 Tools,Resources 和 Prompts 就是同一套 JSON-RPC 换个方法名。


二、M×N → M+N:MCP 到底解决了什么

假设你有 3 个 Agent 客户端、4 个数据源:

graph LR
    subgraph "没有 MCP:M×N 根胶水"
        A1[Agent A] --> T1[GitLab]
        A1 --> T2[数据库]
        A1 --> T3[文件系统]
        A1 --> T4[Slack]
        A2[Agent B] --> T1
        A2 --> T2
        A2 --> T3
        A2 --> T4
        A3[Agent C] --> T1
        A3 --> T2
        A3 --> T3
        A3 --> T4
    end

12 条连线,每一条都是一份要单独维护的对接代码。加一个数据源,3 个 Agent 全要改。

graph LR
    subgraph "有 MCP:M+N 根标准接口"
        B1[Agent A] --> M{MCP 协议}
        B2[Agent B] --> M
        B3[Agent C] --> M
        M --> S1[GitLab MCP Server]
        M --> S2[数据库 MCP Server]
        M --> S3[文件系统 MCP Server]
        M --> S4[Slack MCP Server]
    end

7 条连线。工具方各写一个 MCP server,Agent 方各接一次 MCP client,中间靠协议解耦。加数据源只需新写一个 server,所有 Agent 零改动就能用。 这就是从 M×N 到 M+N 的价值。


三、协议本质:一层 JSON-RPC 2.0,两种传输

MCP 没什么魔法,它就是 JSON-RPC 2.0——每条消息是一行 JSON,带 method、params、id。

角色三分:

两种传输方式:

传输 场景 怎么走
stdio 本地工具(子进程) Host 拉起 server 进程,用它的 stdin/stdout 收发 JSON,一行一条
Streamable HTTP 远程工具(跨机器) 走 HTTP POST,服务端可用 SSE 流式返回

本篇用 stdio 手搓——它最直观,你能亲眼看见字节在管道里怎么流。生产远程场景换成 Streamable HTTP,协议报文完全一样。

一次完整的会话就四类报文(经典握手模型):

方法 方向 作用
initialize client → server 能力协商:我说什么协议版本、我支持什么
notifications/initialized client → server 通知:握手完成,可以干活了(无需回复)
tools/list client → server 发现:把工具清单给我
tools/call client → server 执行:帮我调这个工具

线格式关键点,记死这几条:


四、手搓一个 MCP Server(stdio,不用 SDK)

先不碰 SDK,从零写一个 server,你才知道 SDK 在替你干什么。核心就是一个 stdin 主循环:读一行 → 解析 method → 分发 → 回一行。

工具声明和第 03 篇同构:一个函数 + 一份 JSON Schema。

var tools = []mcpTool{
    {
        Name:        "get_weather",
        Description: "查询某个城市的当前天气",
        InputSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "city": map[string]any{"type": "string", "description": "城市名"},
            },
            "required": []string{"city"},
        },
    },
    {
        Name:        "get_time",
        Description: "返回服务器当前时间",
        InputSchema: map[string]any{"type": "object", "additionalProperties": false},
    },
}

真正执行工具的函数,注意它区分「执行错误」和「未知工具」两种情况:

// runTool 执行工具,返回 (文本结果, 是否为执行错误, 是否未知工具)。
func runTool(name string, args map[string]any) (text string, isErr bool, unknown bool) {
    switch name {
    case "get_weather":
        city, _ := args["city"].(string)
        if city == "" {
            return "错误:city 不能为空", true, false // 执行错误:喂回模型自纠
        }
        return fmt.Sprintf("%s:晴,24°C", city), false, false
    case "get_time":
        return time.Now().Format("2006-01-02 15:04:05"), false, false
    default:
        return "", true, true // 未知工具:走协议错误
    }
}

主循环——铁律是日志一律 stderr,stdout 只放协议报文:

func main() {
    in := bufio.NewScanner(os.Stdin)
    in.Buffer(make([]byte, 0, 64*1024), 4*1024*1024) // 放大缓冲,容纳大消息
    out := bufio.NewWriter(os.Stdout)

    for in.Scan() {
        line := strings.TrimSpace(in.Text())
        if line == "" {
            continue
        }
        var req rpcRequest
        if err := json.Unmarshal([]byte(line), &req); err != nil {
            continue // 不是合法 JSON,忽略
        }
        isNotification := len(req.ID) == 0 // 没有 id 的是通知,不回复

        switch req.Method {
        case "initialize":
            // 能力协商:告诉 client 我说的协议版本、我支持 tools
            writeResp(out, rpcResponse{ID: req.ID, Result: map[string]any{
                "protocolVersion": "2025-11-25",
                "capabilities":    map[string]any{"tools": map[string]any{}},
                "serverInfo":      map[string]any{"name": "demo-server", "version": "0.1.0"},
            }})
        case "notifications/initialized":
            // 握手完成通知,无需回复
        case "tools/list":
            writeResp(out, rpcResponse{ID: req.ID, Result: map[string]any{"tools": tools}})
        case "tools/call":
            var p struct {
                Name      string         `json:"name"`
                Arguments map[string]any `json:"arguments"`
            }
            json.Unmarshal(req.Params, &p)
            text, isErr, unknown := runTool(p.Name, p.Arguments)
            if unknown {
                // 未知工具 → JSON-RPC 协议错误(-32602)
                writeResp(out, rpcResponse{ID: req.ID, Error: &rpcError{Code: -32602, Message: "Unknown tool: " + p.Name}})
                continue
            }
            // 正常/执行错误都放进 result.content,用 isError 区分
            writeResp(out, rpcResponse{ID: req.ID, Result: map[string]any{
                "content": []map[string]any{{"type": "text", "text": text}},
                "isError": isErr,
            }})
        default:
            if !isNotification {
                writeResp(out, rpcResponse{ID: req.ID, Error: &rpcError{Code: -32601, Message: "Method not found: " + req.Method}})
            }
        }
    }
}

一百来行,一个能握手、能列工具、能被调用的 MCP server 就成了。


五、手搓 Client,接到第 02 篇的 Agent 循环上

Server 有了,现在写 client,并把它接到第 02 篇的 Agent 循环上——这一步是关键:证明 MCP 工具能像本地函数一样喂给 LLM。

Client 把 server 当子进程拉起来,接管它的 stdin/stdout 当协议管道:

// startServer 把 server 当子进程拉起,接管它的 stdin/stdout 当协议管道。
func startServer() (*mcpClient, error) {
    cmd := exec.Command("go", "run", "./server")
    cmd.Stderr = os.Stderr // server 的日志透传到我们的 stderr
    stdin, _ := cmd.StdinPipe()
    stdout, _ := cmd.StdoutPipe()
    if err := cmd.Start(); err != nil {
        return nil, err
    }
    return &mcpClient{cmd: cmd, stdin: stdin, stdout: bufio.NewReader(stdout)}, nil
}

发一个带 id 的请求、同步读回响应,就是一问一答:

func (c *mcpClient) call(method string, params any) (json.RawMessage, error) {
    c.nextID++
    req := map[string]any{"jsonrpc": "2.0", "id": c.nextID, "method": method}
    if params != nil {
        req["params"] = params
    }
    b, _ := json.Marshal(req)
    c.stdin.Write(append(b, '\n')) // 一行一个报文
    line, err := c.stdout.ReadBytes('\n')
    if err != nil {
        return nil, err
    }
    var resp struct {
        Result json.RawMessage `json:"result"`
        Error  *struct {
            Code    int    `json:"code"`
            Message string `json:"message"`
        } `json:"error"`
    }
    json.Unmarshal(line, &resp)
    if resp.Error != nil {
        return nil, fmt.Errorf("MCP 错误 %d: %s", resp.Error.Code, resp.Error.Message)
    }
    return resp.Result, nil
}

最妙的一步:MCP 的 inputSchema 和 OpenAI function calling 的 parameters 都是 JSON Schema,几乎一一对应,直接翻译即可:

// toOpenAITools 把 MCP 工具声明翻成 OpenAI function calling 格式。
func toOpenAITools(mts []mcpToolDef) []Tool {
    var out []Tool
    for _, mt := range mts {
        out = append(out, Tool{Type: "function", Function: FunctionDefinition{
            Name:        mt.Name,
            Description: mt.Description,
            Parameters:  mt.InputSchema, // JSON Schema 直接复用
        }})
    }
    return out
}

于是 Agent 循环几乎和第 02 篇一模一样,唯一区别是工具来自 MCP、执行也打回 MCP:

for _, tc := range choice.Message.ToolCalls {
    var args map[string]any
    json.Unmarshal([]byte(tc.Function.Arguments), &args)
    result, err := client.callTool(tc.Function.Name, args) // ← 打到 MCP server
    if err != nil {
        result = err.Error()
    }
    messages = append(messages, Message{Role: "tool", ToolCallID: tc.ID, Content: result})
}

代码里留了个离线自检:不设 OPENAI_API_KEY 也能跑,直接 tools/call 调一次工具,证明协议层已通;有 key 才继续跑完整 Agent 循环。

从 MCP server 发现 2 个工具:
  - get_weather: 查询某个城市的当前天气
  - get_time: 返回服务器当前时间

[离线自检] 直接 tools/call get_weather(上海) → 上海:晴,24°C

跑起来:cd code/mcp && go run .。


六、官方 Go SDK:十几行干完手搓的活

手搓是为了理解协议。生产环境用官方 SDK——github.com/modelcontextprotocol/go-sdk 已在 2026 年发布 v1.0.0 稳定版,由 MCP 团队和 Google 共同维护。同样一个 server,SDK 版长这样:

package main

import (
    "context"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type WeatherArgs struct {
    City string `json:"city" jsonschema:"城市名"`
}

func getWeather(ctx context.Context, req *mcp.CallToolRequest, args WeatherArgs) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: args.City + ":晴,24°C"}},
    }, nil, nil
}

func main() {
    server := mcp.NewServer(&mcp.Implementation{Name: "demo-server", Version: "0.1.0"}, nil)
    // 泛型自动从 WeatherArgs 生成 JSON Schema,不用手写
    mcp.AddTool(server, &mcp.Tool{Name: "get_weather", Description: "查询某个城市的当前天气"}, getWeather)
    server.Run(context.Background(), &mcp.StdioTransport{}) // 握手/list/call 全由 SDK 处理
}

握手、schema 生成、报文分发、错误码——全由 SDK 兜住。手搓那一百行的价值不在于用它上生产,而在于你现在看这段 SDK 代码,知道每个方法背后在传什么字节。

Client 侧同样简洁:

client := mcp.NewClient(&mcp.Implementation{Name: "demo-client", Version: "0.1.0"}, nil)
session, _ := client.Connect(ctx, &mcp.CommandTransport{Command: exec.Command("go", "run", "./server")}, nil)
res, _ := session.CallTool(ctx, &mcp.CallToolParams{Name: "get_weather", Arguments: map[string]any{"city": "上海"}})

七、2026 年的大变化:无状态核心

⚠️ 这是知识盲区最容易踩的地方。 MCP 规范 2026 年迭代很快,本篇手搓用的 2025-11-25 是经典握手模型,好教好懂;但 2026-07-28 发布的规范做了一次破坏性重构,方向是「无状态化」。要点:

变化 旧(2025-11-25) 新(2026-07-28)
会话 有 session 概念 移除 session,核心无状态(SEP-2567)
握手 专门的 initialize + initialized 取消专门握手,首个请求隐式建会话
元数据 放 params 挪进 _meta(protocolVersion、clientInfo、clientCapabilities)
版本声明 握手时一次 每个请求各自声明
列表结果 不可缓存 可缓存(ttlMs、cacheScope、resultType)
roots/sampling/logging 正式能力 标记废弃(12 个月过渡期)

还引入了扩展框架、MCP Apps(server 端渲染 UI)、多轮往返请求(MRTR)、Tasks 等。

给你的实操建议:学习和理解协议,用经典握手模型(清晰);写生产 server,用官方 SDK(它跟着规范走,帮你屏蔽这些变动);只有当你要手写远程 HTTP server 时,才需要仔细读 2026-07-28 规范的无状态部分。别自己手搓生产级协议实现——协议在动,SDK 才是稳定接口。


八、延伸:MCP 之外还有 A2A

MCP 解决「Agent → 工具」,但当你有多个独立 Agent 要互相协作时,需要另一条协议:A2A(Agent2Agent),Google 发起、已捐给 Linux Foundation,和 MCP 同属 LF Agentic AI 基金会。

一句话分工:

协议 方向 解决
MCP 纵向:Agent → 工具/数据 一个 Agent 怎么用外部能力
A2A 横向:Agent ↔ Agent 多个 Agent 怎么互相委派任务

A2A 的核心是 Agent Card:每个 Agent 在 /.well-known/agent.json 暴露一份自我描述(能干什么、怎么调、鉴权方式),别的 Agent 读了就知道怎么把任务派给它。同样走 JSON-RPC 2.0 + HTTP/SSE。

现实检查:今天绝大多数所谓「多 Agent」其实只是一个 orchestrator 在调工具(这正是第 07 篇讲的模式),根本用不上 A2A。只有当你要对接一个你不掌控的、能跨多轮接受任务的第二方 Agent时,才需要 A2A。别为了架构好看提前上。


九、安全:MCP 放大了攻击面

MCP 让 Agent 能接任意第三方 server,这也意味着你把一段别人写的工具描述,直接塞进了模型的上下文。几类真实风险(详见第 10 篇):

防线:来源可信的 server 才装;敏感工具(写操作、转账、删除)走 human-in-the-loop 审批;远程 server 上 OAuth;把 MCP server 当不可信输入审计它返回的每一段文本。


十、决策指南:什么时候该写 MCP Server

不是所有工具都值得包成 MCP server。对照着选:

场景 选择 理由
工具只给自己这一个 Agent 用 直接写 Go 函数工具(第 03 篇) 包 MCP 是过度设计,多一层进程
工具要给多个 Agent / 多个客户端复用 写 MCP Server 一次暴露,处处可用,M+N
要接别人已经写好的能力(GitHub、Slack) 用现成 MCP Server 生态里大概率已有
需要的是「流程/手艺」而非「调用外部系统」 写 Skill(第 11 篇) Skill 管怎么做,MCP 管连什么
要和一个独立自治的第二方 Agent 协作 上 A2A MCP 管工具,A2A 管 Agent 间

小结:MCP 的本质是一根标准协议线,把 Agent 和工具解耦,用 M+N 取代 M×N。手搓一遍你就懂了它不过是 JSON-RPC over stdio——initialize 握手、tools/list 发现、tools/call 执行,stdout 走协议、stderr 走日志。理解用经典模型,生产用官方 SDK,因为协议在 2026 年正快速向无状态演进。工具复用多才值得包 server,单 Agent 自用直接写函数;要连外部系统用 MCP,要定义手艺用 Skill,要跨 Agent 协作才上 A2A。


参考资料

资料 来源
MCP 官方规范与文档 modelcontextprotocol.io
MCP 2026-07-28 规范(无状态核心 SEP-2567) spec.modelcontextprotocol.io
MCP Go SDK v1.0(与 Google 共建) github.com/modelcontextprotocol/go-sdk
Anthropic MCP 发布公告 anthropic.com/news/model-context-protocol
A2A Protocol v1.0 Linux Foundation Agentic AI(a2aproject)
本篇配套代码 github.com/hua-ri/agent-learning /main/mcp